GSTIN Details Retrieval API

This document highlights the GSTIN Details Retrieval API details.

Objective

The GSTIN Details Retrieval API fetches information about a GSTIN, including its status, taxpayer info, e-invoicing eligibility, filing history, tax liability, branch and HSN details.

API URL

https://ind-engine.thomas.hyperverge.co/v1/GSTINDetailsRetrieval

API Endpoint

GSTINDetailsRetrieval

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files as form-data through a POST request.

Authentication

You need a unique pair of application ID (appId) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

API Request Details

Method - POST

Headers

Parameter	Mandatory or Optional	Description	Allowed Values
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value
transactionId	Mandatory	A unique identifier for tracking a user journey	This should be both unique and easily associated with the user's journey in your application(s)

Inputs

The following table provides the complete information on the parameters used in the request body for the API calls.

Parameter	Description	Mandatory or Optional	Allowed Values	Default Value
gstin	The Goods and Services Tax Identification Number (GSTIN) of the customer	Mandatory	Type: String Length:15	Not Applicable
hsnDetails	Indicates whether HSN (Harmonized System of Nomenclature) details are required	Mandatory	Type: String enum: "true" or "false"	Not Applicable
branchDetails	Indicates whether branch details are required	Mandatory	Type: String enum: "true" or "false"	Not Applicable
filingDetails	Indicates whether filing details are required	Mandatory	Type: String enum: "true" or "false"	Not Applicable
liabilityPaidDetails	Indicates whether liability paid details are required	Mandatory	Type: String enum: "true" or "false"	Not Applicable

Request

The following code shows a standard cURL request for the API.

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/GSTINDetailsRetrieval' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "gstin": "<Enter_the_GSTIN>",
    "hsnDetails": "<Enter_True/False>",
    "branchDetails": "<Enter_True/False>",
    "filingDetails": "<Enter_True/False>",
    "liabilityPaidDetails": "<Enter_True/False>"
}'

Success Responses

Flags set to True

The provided GSTIN is valid, and all four flags are set to true.

{
  "status": "success",
  "statusCode": "200", 
  "result": {
    "basicDetails": {
      "gstin": "<GSTIN>",
      "ekycFlag": "<eKYC_Flag>",
      "compositionRate": "<Composition_Rate>",
      "percentTaxInCash": "<Percent_Tax_In_Cash>",
      "aggreTurnOverFY": "<Aggregate_Turn_Over_Financial_Year>",
      "registrationType": "<Registration_Type>",
      "aggreTurnOver": "<Aggregate_Turn_Over>",
      "businessNature": [
        "<Business_Nature_1>",
        "<Business_Nature_2>",
        "<Business_Nature_3>"
      ],
      "registrationDate": "<Registration_Date_in_DD/MM/YYYY_Format>",
      "registrationStatus": "<Registration_Status>",
      "percentTaxInCashFY": "<Percent_Tax_In_Cash_FY>",
      "memberDetails": [
        "<Member_1>",
        "<Member_2>",
        "<Member_3>"
      ],
      "natureOfCoreBusinessActivity": "<Nature_Of_Core_Business_Activity>",
      "aadhaarVerified": "<Aadhaar_Verified>",
      "legalBusinessName": "<Legal_Business_Name>",
      "constitutionOfBusiness": "<Constitution_Of_Business>",
      "tradeName": "<Trade_Name>",
      "centralJurisdiction": "<Central_Jurisdiction>",
      "isEInvoiceMandated": "<Is_E_Invoice_Mandated>",
      "stateJurisdiction": "<State_Jurisdiction>",
      "cancellationDate": "<Cancellation_Date>",
      "isEInvoiceOpted": "<Is_E_Invoice_Opted>"
    },
    "hsnDetails": {
      "goods": null,
      "services": [
        {
          "hsnCode": "<HSN_Code>",
          "hsnDescription": "<HSN_Description>"
        },
        {
          "hsnCode": "<HSN_Code>",
          "hsnDescription": "<HSN_Description>"
        }
      ]
    },
    "branchDetails": {
      "message": "<Message>",
      "principalAddress": {
        "address": "<Principal_Address>",
        "natureOfBusiness": "<Nature_Of_Business>"
      },
      "additionalAddresses": []
    },
    "filingDetails": {
      "filingStatus": [
        [
          {
            "finYear": "<Financial_Year>",
            "returnType": "<Return_Type>",
            "returnPeriod": "<Return_Period>",
            "modeOfFiling": "<Mode_Of_Filing>",
            "dateOfFiling": "<Date_Of_Filing_in_DD/MM/YYYY_Format>"
          }
        ]
      ]
    }
  }
}